Summary

This PR is a broad perceived-performance pass for the scheduling and plan-building workflows. The goal is to make the app feel closer to Linear-style local-first interactions while still respecting that Planning Center itself can be slow.

The main strategy is not a new vendor or external cache. Instead, this uses optimistic UI, local warm caches, React Query cache hydration, request dedupe, targeted prefetching, and delayed reconciliation so the user sees immediate feedback while the slow network work finishes in the background.

Strategy

1. Make mutations feel instant

Scheduling, status changes, unscheduling, and plan item edits now update the local UI immediately before Planning Center responds.

• Scheduling a person inserts/updates that person in the selected people list and team-position slot cache immediately.
• Status changes update both people and filled-position caches optimistically.
• Unscheduling removes the assignment from visible caches immediately.
• Plan item create, add-song, edit, delete, and reorder paths now update the Plan tab cache optimistically.
• Failed mutations restore the prior cache snapshot.
• Successful mutations reconcile optimistic IDs with Planning Center IDs when needed.

2. Stop making active views wait on immediate refetches

The old flow often invalidated and refetched the active view immediately after a write, which made successful actions feel like they flickered or stalled.

This PR keeps inactive queries invalidated, but delays active-view reconciliation briefly. The visible screen stays optimistic and responsive, then quietly refetches after the interaction settles.

3. Use warm local snapshots without breaking hydration

A set of small localStorage-backed caches now covers the expensive read paths:

• schedule catalog and plans
• team positions
• people lists and people search
• people dashboard and person details
• plan items
• song search and song option metadata
• account panel, org time zone, and my scheduled plans

Those caches hydrate React Query after mount through a shared helper so the first client render still matches SSR. This avoids React hydration warnings while preserving fast warm starts.

4. Reduce Planning Center request volume

Shared Planning Center service wrappers now dedupe or cache high-volume reads:

• core GET request in-flight dedupe
• service type and team position catalog caching
• plan item read caching and invalidation after writes
• people assignment validation, roster, search, plan-times, blockout, and schedule-history caches
• plan range caching
• song catalog, song detail, arrangement/key, and normalized search result caching

Caches return defensive clones so callers cannot accidentally mutate shared cached data.

5. Prefetch where intent is clear

Several UI paths now warm the next likely data before the user clicks:

• schedule root prefetches plan, team-position, plan-item, and people-history data
• People page prefetches detail views on hover/focus/touch
• Plan tab prefetches song option metadata for visible songs
• Song picker prefetches options for hovered/focused songs
• schedule candidate and slot interactions prefetch likely next views

6. Make loading states stable instead of jarring

This adds route-shaped Suspense fallbacks for schedule pages and uses placeholder data to avoid tearing down whole views during selection changes.

Hydration issues found during browser verification were also cleaned up:

• account panel and People nav cache reads now happen after mount
• query cache hydration is post-mount instead of initial-render initialData
• randomized sidebar skeleton widths were replaced with deterministic widths

7. UI hygiene from the performance pass

The Plan page row interaction areas changed during the optimistic Plan work, so this PR also cleans them up:

• dedicated left-side grip handle for drag/reorder
• item body is the edit click target
• delete is a separate, compact right-side action
• row hover styling applies to the cohesive row surface again
• placeholder Plan data disables mutation controls so cached rows cannot be edited for the wrong selected plan

Behavior changes

• Scheduling and Plan tab mutations appear immediately and roll back on error.
• Active screens no longer immediately flicker through a forced refetch after every write.
• Warm revisits should show useful cached data faster.
• Browser console no longer reports hydration warnings on the verified May 31 plan page.
• Plan rows have clearer edit/reorder/delete zones.

Safety notes

• No new SaaS/vendor dependency was added.
• Browser verification was read-only against the May 31 service. I did not reorder, schedule, unschedule, edit, or otherwise mutate Planning Center data during browser checks.
• Local persisted caches are cleared on account switch and after writes that can make snapshots stale.

Test coverage

Added or expanded focused tests for:

• optimistic schedule cache updates and delayed reconciliation
• optimistic Plan item cache updates, rollback, no-op save/reorder guards, and cache clearing
• local cache serialization/parsing for schedule catalog, people, dashboard, plan items, songs, team positions, org time zone, and account panel
• core GET in-flight dedupe
• Planning Center service read caches and defensive clone behavior
• song search result caching
• people dashboard hydration bounds
• route timing helpers

Verification

• bun run lint
• bun run typecheck
• bun run test
• git diff --check
• Read-only browser smoke on http://localhost:3000/schedule/plan?serviceTypeId=78289&planId=86407886&teamId=260369&positionId=1314760&view=plan
  • rendered May 31 plan page
  • verified Plan tabs and rows are present
  • verified no new console warnings/errors after reload